home *** CD-ROM | disk | FTP | other *** search
/ Aminet 45 / Aminet 45 (2001)(GTI - Schatztruhe)[!][Oct 2001].iso / Aminet / game / role / ldmud-3.2-bin.lha / mud / doc / efun / sprintf < prev    next >
Text File  |  2001-07-18  |  6KB  |  110 lines
  1. SYNOPSIS
  2.         string sprintf(string fmt, ...)
  3.  
  4. DESCRIPTION
  5.         Most of the characters in the format string <fmt> get passed
  6.         straight through to the output (ie: printed or put in the
  7.         return string), to format the arguments into the string it's
  8.         necessary to include an argument format string (AFS) in the
  9.         FMT.  An AFS is a series of characters starting with a percent
  10.         sign "%" and terminated with a argument type specifier.
  11.         To include a "%" sign in the output, it is necessary to include a
  12.         double percent sign "%%". The sequence "%^" will output "%^" again.
  13.  
  14.         Valid argument type specifiers are:
  15.           "s" : the argument is a string.
  16.           "d" : the argument is an integer to be included in decimal
  17.                 representation.
  18.           "i" : same as "d".
  19.           "o" : the argument is an integer to be included in octal
  20.                 representation.
  21.           "x" : the argument is an integer to be included in hexidecimal
  22.                 representation.
  23.           "X" : as "x" except letters are capitalised.
  24.            e,E,f,F,g,G like in c.
  25.           "O" : the argument is an LPC datatype to be printed in an arbituary
  26.                 format, this is for debugging purposes.
  27.  
  28.                 If the argument is an object then the function printf_obj_name() on
  29.                 the master object is called with the object as a parameter, the string
  30.                 returned is included in brackets at the end of object file name.
  31.                 If 0 is returned then nothing is appended after the file name.
  32.  
  33.                 Between the percent sign and the argument type specifier in
  34.                 the AFS, the following modifiers can be included to specify
  35.                 the formatting information.  Order is not important unless
  36.                 otherwise specified.  "n" is used to specify a integer, which
  37.                 can be a "*" in which case the next argument is used as the
  38.                 number.
  39.  
  40.         Modifiers:
  41.            n    specifys the field size. If the size is prepended with
  42.                 a 0, the argument is printed with leading zeroes.
  43.           "."n  specifies the presision, for simple (not columns or tables)
  44.                 strings specifies the truncation length.
  45.           ":"n  n specifies the fs _and_ the presision, if n is prepended by a zero
  46.                 then the pad string is set to "0".
  47.           "'X'" the pad string is set to the char(s) between the single quotes,
  48.                 if the field size is also prepended with a zero then which ever
  49.                 is specified last will overrule.
  50.                 NOTE:  to include "'" in the pad string, you must use "\\'"
  51.                 (as the backslash has to be escaped past the interpreter),
  52.                 similarly, to include "\" requires "\\\\".
  53.           " "   pad positive integers with a space.
  54.           "+"   pad positive integers with a plus sign.
  55.           "-"   left adjusted within field size.
  56.                 NB: std (s)printf() defaults to right justification, which is
  57.                     unnatural in the context of a mainly string based language
  58.                     but has been retained for "compatability" ;)
  59.           "|"   centered within field size.
  60.           "="   column mode.  Ignored unless the argument type specifier is s.
  61.                 Field size must be specified, if precision is specified then it
  62.                 specifies the width for the string to be wordwrapped in, if not
  63.                 then the field size is.         The field size specifies the width of
  64.                 the column and has the effect that the last line of the column
  65.                 is padded with spaces to achieve this length.
  66.           "#"   table mode.  Ignored unless the argument type specifier is s.
  67.                 Field size must be specified, if presision is specified then it
  68.                 specifys the number of columns in the table, otherwise the
  69.                 number is "optimally" generated.  Table mode is passed a list
  70.                 of slash-n separated 'words' which are put in a format similar
  71.                 to that of ls.
  72.           "@"   the argument is an array.  the corresponding AFS (minus all
  73.                 "@") is applied to each element of the array.
  74.  
  75.         When the formatting of an element results in several output lines
  76.         (column or table mode) and no explicite pad strings has been
  77.         defined, then the efun removes any padding whitespace before
  78.         the newlines of all but the last line. However, if an explicite
  79.         pad string has been given, even if it is the simple ' ', then
  80.         the padding will not be removed.
  81.  
  82.  
  83. EXAMPLES
  84.         sprintf("decimal=%d, octal=%o, hexadecimal=%x\n", 7, 7, 7);
  85.  
  86.         sprintf("array=%O\n", ({1, 2, 3}));
  87.         this will return the following:
  88.         ({ /* sizeof() == 3 */
  89.           1,
  90.           2,
  91.           3
  92.         })
  93.         An array will be printed recursively and each element of the
  94.         array will be indented. Can also be used as a debugging tool.
  95.  
  96.         sprintf("%-*#s\n", 80, implode(get_dir("~/."), "\n"));
  97.           Produces a table with the filenames from directory ~/. .
  98.  
  99.         sprintf("%-=3s", "fo bar") --> "fo\nbar"
  100.         sprintf("%-=' '3s", "fo bar") --> "fo \nbar"
  101.  
  102. HISTORY
  103.         LDMud 3.2.9 added the "%^" sequence for compatibility with
  104.           terminal_colour(), clarified the meaning of leading
  105.           0s in the field size modifier, and clarified the interaction
  106.           between the padding and newlines.
  107.  
  108. SEE ALSO
  109.         printf(E), terminal_colour(E)
  110.